Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 017 / bat203.lbr / batlist.lst < prev

Wrap

File List | 2011-01-30 | 40KB | 1,136 lines

BATLIST.DOC =BATLIST.LST BAT - AN EXTENDED BATCH FACILITY V1.02 Frank J. Canova Jr. Dept.26p / 031-3 Boca Raton, FL BCRVM1(VM212544) INTRODUCTION ____________ There is a deficiency in DOS batch files which I couldn't stand to see. That is, they are very dumb. I am a user that loves to see a user friendly interface in order to talk to my programs. There seemed to be almost no way to do this with batch files. Because of the lack of control one has over batch files, I created this extended batch facility, or BAT for short. With it, you have the ability to do . . . * String concatination * Simple expressions and substitutions * Looping of tasks * Better control of messages to the screen * Return Codes * Simple conditionals * Serch for files or tell if they exist * Accept responces from the user Described in these pages is my solution to batch files. I hope that you will find it useful as well. The user of VM/370 will note an amazing similarity to EXECs . . . why spoil a good thing?! Improvements ____________ I am very aware that many improvements can be made. To the best of my knowledge, this program works as advertised. Please don't bug me too much about making improvements since I am probably aware of what they already are. Although there may be some enhancements to BAT . . . don't expect it to get to the level of VM/370. This is all on my own time ya' know! Classification ______________ The BAT program was written in its entireity on my own time and my own equipment. Please feal free to distribute it freely to your colleagues and members of you local IBM personal computer club. I reserve all rights to this program although I do not presently have plans to submit this software to be published. 1 DOS Dependency ______________ This level of BAT executes only with DOS 1.1. BAT is restricted as to which DOS levels it can run with because of the high amount of parameter passing to/from COMMAND.COM that is necessary. If you run with the wrong level of DOS, you will get an error message. HOW BATCH FILES ARE EXECUTED ____________________________ Batch files are files which normally contain a series of commands which is read from the file and entered through DOS just as if the user had typed the line. It's primary function was to save the user time and trouble from having to enter a repetative series of commands to the system to perform some task. With the extended batch facility (BAT), the batch file can now contain not only these same repetative DOS commands, but control commands, prompts, and other misc. parameters. In general, it gives the user more frendly control over programs in his system. The extensions to batch processing is accomplished by adding a control program BAT.COM which will gain control of batch processing and interpret the new commands within the batch file. Note that this program should be resident on the same disk that the batch file is. Basicaly, all extended batch file commands start with the word 'BAT' in the batch file, and all other commands (DOS or otherwise) do not start with 'BAT'. To be more exact, when a batch file starts running, all commands are executed from DOS just as any batch file would. When it comes across a statement which starts with 'BAT', it loads in the extentions from the file BAT.COM which then starts execution. The BAT program takes the remainder of this line and the entire contents of all other lines and starts execution in the following fashion. <empty line> - If a line from the batch file contains nothing (just a CR LF) then the line is skipped and the next line is read in. This may be used to make a batch program more readable. BAT <empty line> - If a line from the batch file contains just the BAT keyword then the line will also be skipped. Note that leading spaces or tabs will be allowed before the keyword BAT. BAT <command token> <operand token> - This is the normal format for an extended batch command line. Not all commands have operands (eg. BEGTYPE, CLS) and some commands may have several (eg. IF, TYPE, etc). Note that leading spaces or tabs will be allowed before the keyword BAT. 2 <dos command line> - If the line is not an empty line and does not start with the keyword BAT, then it is considered to be a DOS command. The DOS command is executed by setting it's text pointers back to the beginning of the line and then BAT.COM terminates. This causes DOS to read and interpret the batch line in the standard way. This continues until a DOS batch file statement contains BAT as it's first word which causes DOS to reload the extended batch facility. BAT.COM would then continue to interpret the remainder of that line with the rules above. It will again continue to interpret lines as long as they are either empty or contain the keyword BAT. THE CONCEPT OF A TOKEN. _______________________ Since the entire extended batch facility processing is performed by observing tokens from the batch file, the concept of tokens is very important. Basically, a token is a string of characters whose final form has a limit of 15 characters. The token can be built up by any combination of literal characters or variables. Literal characters are all the printable characters on your keyboard. Upper or lower case characters mean the same thing to BAT and can be used interchangeably. If you print a token out, you will see them in upper case. For instance, the characters wXyZ will create a token which if printed will be WXYZ. Variables may also be used to create tokens. Built into the system are eleven variables. These are %0 to %9 and a special variable called %R. See the section on variables for more details about their uses. Each variable can contain up to 15 characters and when used as a token, will result in creating a token with the contents of that variable. For instance, if %0 contains the characters ABC, then using the token %0 in a batch file will be just like you had entered ABC in it's place. Literal characters and variables can be combined to form tokens as well. This is done by putting the variables and literals beside each other in the batch file without spaces. This will concatinate these strings, performing the proper substitutions for variables, and create a token of not more than 15 characters. Trailing characters will be truncated without errors if this limit is exceeded. 3 As an example, if %0 contains ABC, %1 contains XYZ, and %2 is empty, the following will result: BATCH FILE CONTAINS RESULTING TOKEN IS Abc ABC %1 XYZ 123%1 123XYZ %0123%1 ABC123XYZ %0%2%1 ABCXYZ 123 %1 123 XYZ The last example actually creates two seperate tokens since a space existed before the percent sign in the batch file. These tokens which result are used within the commands described later to control the actions or results they produce. If %1 contains XYZ again, then a batch file which contains . . . BAT TYPE ABC 123%1 produces on the display . . . ABC 123XYZ VARIABLES _________ Eleven variables are available to BAT. These are marked in a batch file with a percent sign. Any of the following are valid variable names: %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 %R The last variables is for return codes and is a special case which will be discussed later. In general, however, each variable can contain a string of 0 to 15 characters. In the event that you wish to use a percent sign within a batch file without being taken as a variable name, then two percent signs are needed. That is, the statement: BAT TYPE A percent sign is like %% Would show: A PERCENT SIGN IS LIKE % When batch processing begins, DOS initialized the variables based on the original command line which invoked the batch file. For example, for a batch file called TEST1, the following assignments are made: 4 For the command line . . . TEST1 DATAA DATAB The variable would be initialized to %0 TEST1 %1 DATAA %2 DATAB %3 to %9 would be empty The batch file can then alter the contents of any of these variables through BAT. When they are altered, a DOS command within the batch file can make use of the new value. Lets say the mentioned batch file (TEST1) contains the following statements: BAT TYPE Now creating a backup of %1 BAT %3 = %1.TMP COPY %1 %3 When invoked, the batch file would create a new variable (%3) which is passed back to DOS for the COPY command. When it is executed, the following will be seen on the screen: User types: TEST1 DATAA DATAB Batch responds: NOW CREATING BACKUP OF DATAA A> COPY DATAA DATAA.TMP RETURN CODES ____________ There is a special variable %R for return codes. This return code is intended for both extended batch commands and users routines. It can indicate to an extended batch file what action should be taken as a result of some condition such as a program abend, normal or abnormal execution, etc. The user routine can setup a return code for BAT by saving it's value at location 0000:04FE. The return code is one word long and results in a hex value for the variable %R. This special variable can not be stored into via BAT, only recalled from. So while a statement like %9 = %R is valid, %R = %9 is not valid. The following portion of a BASIC program can be used to set up a return code before it exits. . 2000 DEF SEG=0 : POKE H04FE,H2B 'Setup return code of 2B 2010 DEF SEG 'Restore basic's seg 2020 SYSTEM 'Return to DOS to do more batch file . 5 When BASIC exits and batch processing resumes, the extended batch commands allow for a test on the return code to control processing. A sample batch file which might check it's result would be: BASICA SETRC BAT IF %R = 2B TYPE The basic program exited abnormally. BAT IF %R = 0 TYPE ** Congrat's - You had a normal exit! ** Note that %r contains hex, not decimal values. Also note that leading zeros are striped from %R before then token is generated. For further examples of how return codes are used, see the description of the command STATEOF. EXTENDED BATCH FILE COMMANDS ____________________________ The following list summarizes the available commands that are available within the extended batch file facility. A detailed description follows. BAT CLS BAT BEGTYPE ...[text]... END BAT DEC [variable] BAT EXIT BAT GOTO [-label.token] BAT IF [token1] [compare.token] [token2] [statement] BAT INC [variable] BAT READ [variable]...[variable] BAT SKIP [num.of.lines] BAT STATEOF [filename.token] BAT TYPE [text.token]...[text.token] BAT -[label.token] [statement] BAT [variable] = [assignment.token] BAT * [comment] 6 COMMAND: CLS FUNCTION: Clears the screen. DESCRIPTION: The screen type (color 40, color 80, mono, etc) is sensed via BIOS and this screen type is reset. This results in clearing the screen of data. This is very useful when creating prompts on the screen for the user and is often used just before the commands TYPE or BEGTYPE. The remainder of the line after the word CLS is ignored. RELATED COMMANDS: TYPE, BEGTYPE EXAMPLES: BAT CLS BAT BEGTYPE This is a prompt for the user. He will see it on a new clear screen. end COMMAND: BEGTYPE [..text..] END FUNCTION: Types a series of lines directly from the batch file. DESCRIPTION: The remainder of the line after the command BEGTYPE is ignored and scanning begins with the next line. A line of text is read from the batch file and the line is printed to the screen unless the line begins with 'END'. The word END indicates that there are no more lines of text to be printed. Either case is allowed for the word END. Note that when END is the first thing on the line, nothing else is allowed before it. Spaces and tabs are the only characters allowed before this word. This command is very useful for printing a long series of text to the user, usually a prompt or menu. The characters will appear exactly as in the batch file, spaces, case, and control characters are preserved. RELATED COMMANDS: CLS, TYPE EXAMPLES: BAT CLS BAT BEGTYPE This is a prompt for the user. It will be seen on a new clear screen because of CLS You may ask the user to select an option here: 1 - First option 2 - Second option. End 7 Note the the final word END starts the last line. All text between the BEGTYPE line and the END line will be seen on the screen exactly as typed. COMMAND: DEC [variable] FUNCTION: To decrement a decimal number contained in a variable. DESCRIPTION: The purpose of this command is primary for controling loops within batch files and for possibly going through sequences of file names. It does a decrement on the CONTENTS of a variable which is the operand of this command. The special variable %R is not allowed as an operand. Note that with this command, the string length of the variable will never change. That is, the decrement of the number 100 is 099. The user must supply as many zeros as needed to allow for the maximum number. Remember that there is a 15 character limit on strings so the smallest number is 000000000000000 and the bigest number is 999999999999999! With a variable that contains just a 0, the corresponding maximum number for this variable would be 9. Note that compares are done between character strings and not the value of them. This means that 000 and 00 would not be found equal. It will only decrement the numeric part of the variable. For example, if the variable contains the string PROG100 then the decrement of this string is PROG099. The alphanumeric portion of the variable will not be altered. In addition, numbers to the left of any letters will also not be altered. If the variable contains only letters or is empty, no change will occur. RELATED COMMANDS: IF, INC, Assignments EXAMPLES: BAT %1 = 10 BAT DEC %1 BAT %2 = XYZ3PROG00 BAT DEC %2 BAT TYPE %1 %2 After this batch file is run, the following would be seen on the screen: 09 XYZ3PROG99 The following batch file will print the numbers 4 to 0 on the screen. BAT %1 = 5 BAT -LOOP DEC %1 BAT TYPE %1 BAT IF %1 0 GOTO -LOOP 8 COMMAND: EXIT FUNCTION: To terminate the batch file. DESCRIPTION: Exit requires no operands, and will immediately terminate the batch file from being processed further and DOS will show a prompt for accepting new commands from the user. The 'double prompt' symptom of the standard batch file exits will not appear. The use of this command is to return to DOS in the middle of a batch file. It is not necessary to use this command at the end of batch files. The normal end of file mark within the file will also exit in the same manner. RELATED COMMANDS: IF EXAMPLES: BAT TYPE Would you like to exit? (Y/N) BAT READ %9 BAT IF %9 = Y EXIT . In the above example, the user is prompted to see if he would like to exit the batch file before continuing. If he types 'Y' and presses enter, the compare will match and the batch file will end. Otherwise, processing will continue. COMMAND: GOTO [-label.token] FUNCTION: To change the flow of execution within the batch file. DESCRIPTION: The operand following the command GOTO is tokenized. The resulting token must have '-' (minus) as it's first character. This identifies it as a valid label name. The batch processor will then start scanning at the top of the batch file for this label. If it is found, command execution will resume processing at this line. If it is not found, an error will result. Note that because of the overhead involved in doing this branch, the GOTO should not be heavly used at the end of a long batch file. RELATED COMMANDS: IF, SKIP EXAMPLES: BAT -LOOP BAT TYPE This line is constantly being printed. BAT GOTO -LOOP 9 COMMAND: IF [test1.token] [compare.token] [test2.token] [...stmts...] FUNCTION: To test for various conditions in order to alter the way the batch file executes. DESCRIPTION: Three tokens are expected after the command word IF. The first and third are tokens that are held temporally while the compare is being made. The second token must either be the characters '=' or '<>'. This corresponds to equal and not-equal respectively. For an equality to exist between two strings, then must match exactly in both contents and length. If the comparison is correct, then the statement that follows the IF command will be executed. This may be ANY batch command. Note that the statement following the IF does not contain the keyword 'BAT'. If the comparison is incorrect, then the remainder of the line is skipped and command execution will resume with the next line. RELATED COMMANDS: GOTO, SKIP, INC, DEC, TYPE, EXIT, STATEOF EXAMPLES: All of the following IF statements will compare correctly: BAT %1 = ABC BAT %2 = BAT IF ABC = %1 TYPE The variable contains ABC. BAT IF 0 <> 00 TYPE These are different lengths. BAT IF AABCD = A%1D TYPE Token substitutions are made. BAT IF %2 <> %1 TYPE Variables are different lengths. BAT IF .%2 = . TYPE This matches if var is empty. BAT IF BOX = BOX IF DOG <> CAT TYPE Did multi-if compare. COMMAND: INC [variable] FUNCTION: To increment the numeric contents of a variable. DESCRIPTION: This command will increment the portion of the variable which is numeric. It is intended for looping within the batch file or for generating new increments of a file name. It requires a variable as an operand. The special variable %R is not allowed. Refer to the DEC command for details of operation and the limitations it has. RELATED COMMANDS: DEC, IF, Assignments EXAMPLES: BAT %1 = 997 BAT -LOOP INC %1 BAT TYPE %1 BAT IF %1 003 GOTO -LOOP 10 This batch program will print this sequence of numbers on the screen: 998 999 000 001 002 003 FUNCTION: To accept a responce from a user and assign it to one or more variables. DESCRIPTION: When the command word READ is seen in the batch file, an input line is accepted from the user. All function keys are assigned to the normal DOS edit functions. When ENTER is pressed, the input line is tokenized. Because it is tokenized, several things are done to the responce. First, all lower case characters are converted to upper case. Second, if a variable name exists in the input line, it will get substituted with the contents of the variable. Third, words will be isolated with spaces as delimiters. Therefore a responce of 'THIS IS MY ANSWER' will be assigned four seperate tokens. Once the responce is tokenized, each token will be assigned in order to the variables indicated after the READ command. When there are no more variables after the READ command to assign, ther remainder of the responce is thrown away. The special variable %R is not allowed as an argument of the READ command. If there is more variables to be assigned after the READ command than there are tokens from the input, these variables will be cleared out to a empty state. Note that there does not have to be any variables indicated after the command READ. In this case, BAT would wait for the enter key, throw away any responce, then continue to process the next batch file command. This is useful for pausing within the batch file. RELATED COMMANDS: BEGTYPE, IF, TYPE EXAMPLES: BAT -again TYPE Type your first and last name. BAT READ %1 %2 BAT IF .%1 = . GOTO -again BAT TYPE Hello %1 %2 User sees: TYPE YOUR FIRST AND LAST NAME. User just presses enter: (Variable %1 will be empty, so the IF command will cause execution to restart from the '-again' label.) User sees: TYPE YOUR FIRST AND LAST NAME. User enters: frank canova jr. 11 User sees: HELLO FRANK CANOVA (Note that the 'jr.' is droped since there is no variable for it to be assigned to. COMMAND: SKIP [num.of.lines] FUNCTION: To do a forward jump by the specified number of lines. DESCRIPTION: This command does a forward jump only. It should be used instead of the GOTO command where ever possible since it will execute much faster, especially in large batch files. The operand for this command is a decimal amount of lines to be skipped. This value is NOT a token. It may be a number between 0 and 9999. If a skip amount is so large that it will cause it to go past the end of the batch file, batch execution will terminate (a poor coder's way of doing an EXIT command!). RELATED COMMANDS: GOTO, IF EXAMPLES: BAT -top READ %1 BAT IF .%1 <> . SKIP 2 BAT TYPE You must give a responce, try again. BAT GOTO -top BAT TYPE Thank you for your reply. In the above example, if the user enters nothing to the READ command, the comparison at the IF will fail and a message is printed. The GOTO command is needed here because it is a backward reference jump. However, if the user does enter something, the SKIP command will jump over these two lines which would print the 'thank you' message. COMMAND: STATEOF [filename.token] FUNCTION: To serch the diskettes to see if a file exists. DESCRIPTION: This command is one of the most complex and powerful of the capabilities of BAT. First, the operand of the command is tokenized. This operand is a file name. It may be one of several forms: A very general name with 'wildcards' (e.g. *.* or BA?.* or *.COM); Or it can be a specific file name without a drive specifier (e.g. BAT.COM, BATDEMO.BAT, etc.); Or it can be a file name with a specific drive (e.g. A:BAT.COM, B:*.*, etc.). If there is a specific drive in the file name, then this will be the only drive that will be serched. If there is no drive specified, then all drives will be serched, first with the default drive, then with all remaining drives starting with A and ending with D. For instance, if B is the default drive, the serch order will be B, A, C, D. If a 12 drive is not installed, it will be skipped. If a drive is installed but does not have a diskette in place, then a timeout error will occur which causes the drive to be ignored. As the diskette is serched, as scan is made of the directory for the first match of the file name given. For any 'wildcards' in the file name, any directory entry will match as long as the 'non-wildcard' characters match the entry exactly. That is, if the file to be serched for is BA*.*, then both BAT.COM and BATDEMO.BAT will match, but COMMAND.COM will not. When a directory match is found, the entire file name will be assigned to the last variable name in the original operand for this command. That is, if the variable %9 contains '*.*', then after the batch command 'STATEOF %9' is executed, then the variable will most likely contain 'A:COMMAND.COM' which is the first directory entry it finds that matched the original file name. If no variable existed in the original batch command, such as 'STATEOF TEST.DAT', then no assignment will be made. The special variable %R, which is used for return codes, will indicate if a file was found. After STATEOF executes, one of the following return codes will be found: 0 - The file was found. No switch had to be made to an alternated drive in order to find a directory match. 1 - The file was not found. If a specific drive was originally specified, then the requested file might still exist on another drive, but was not serched. If no specific drive was specified, then the file was not found after serching all available diskettes. 9 - An invalid file name was given. For example 'E:TEST.DAT' specifies an invalid drive. A - Same as return code 0, but the STATEOF command had to switch to drive A to find the file. B - Same as A but was found on drive B. C - Same as A but was found on drive C. D - Same as A but was found on drive D. 13 RELATED COMMANDS: READ, IF, TYPE EXAMPLES: BAT STATEOF %9 = *.FIL BAT TYPE Test1 RC=%r filename= %9 BAT %9 = *.COM BAT TYPE Test2 serching for %9 BAT STATEOF %9 BAT TYPE Test2 RC=%r, filename= %9 BAT %1 = B*.* BAT %2 = BAT STATEOF %1%2 BAT TYPE Test3 RC=%r, filename1= %1, filename2= %2 If the diskette A contains COMMAND.COM and diskette B contains BAT.COM and diskette A is the default drive, the following will be printed from the previous batch file. TEST1 RC=1 FILENAME= *.FIL TEST2 SERCHING FOR *.COM TEST2 RC=0, FILENAME= A:COMMAND.COM TEST3 RC=B, FILENAME1= B*.*, FILENAME2= B:BAT.COM COMMAND: TYPE [text.token] ... [text.token] FUNCTION: To print on the screen messages and the contents of variables. DESCRIPTION: The TYPE command accepts any number of tokens as operands. Read the description on tokens to find out the many variations of their format. Basically however, character literals, any variable (including %R), and any combination of them can be printed. After the line is tokenized, each token is printed in upper case. Only one space will seperate each token. If a variable is empty and is printed out, an additional space will appear. RELATED COMMANDS: BEGTYPE EXAMPLES: BAT %1 = hello BAT TYPE this IS some TEXT BAT TYPE The current variable %%1 = %1 BAT TYPE The current return code is %r When executed, the following will appear on the screen: THIS IS SOME TEXT THE CURRENT VARIABLE %1 = HELLO THE CURRENT RETURN CODE IS 0 14 COMMAND: [-label.token] [statement] FUNCTION: This is the destination of a jump via the GOTO command. DESCRIPTION: This label is not actually a command, but the format for any standard statement. The label itself is a token whose first character is a '-' (minus) sign. Normally during batch file processing, when a line contains a so called command of this format, it is skipped and the next token is used as the command. When a GOTO command is processed, the entire batch file will be scanned starting from the top for this label. When found, scanning stops and batch file processing will resume with this line. For example, with the statement: BAT -SELF GOTO -SELF. The word BAT identifies the line as a non-DOS command. The first -SELF is seen as a label and skipped, the next token will be taken as the command. Then GOTO is seen as the command whose operand is the next token - SELF. This batch line, of course, will execute in an infinite loop. RELATED COMMANDS: GOTO EXAMPLES: BAT -TOP BAT TYPE Select A, B, or X BAT READ %9 BAT GOTO -%9 BAT -A TYPE you selected option a. BAT GOTO -TOP BAT -B TYPE you selected option b. BAT GOTO -TOP BAT -X EXIT BAT -%9 TYPE you didn't select the proper option. BAT GOTO -TOP Note that you do not have to have a statement after the label. Note also that in the above example, since the label is a token, the label '-%9' will always match if the others do not. COMMAND: [variable] = [assignment.token] FUNCTION: To assign a variable a string value. DESCRIPTION: If the first character in the command is a '%' (percent), then it is consitered to be an assignment statement of the above form. The next token on the line must be an equal sign. The third token is any of the possible variations on tokens described previously. This third token does not have to exist. In this case, the token is consitered to be empty. The resulting third token is then moved to the first variable. 15 The first variable cannot be the special variable %R, but may be any of the other variables %0 to %9. If a DOS command is later executed and uses one of these variables, it will be properly replaced with the contents of that variable. RELATED COMMANDS: IF, TYPE EXAMPLES: BAT %1 = ABC BAT %2 = DEF BAT %3 = ANS=%1%2 BAT TYPE %1 %2 %3 When the resulting batch file is run, the following will be seen on the screen: ABC DEF ANS=ABCDEF COMMAND: *[comment line] FUNCTION: To allow comments to be seen in the batch file. DESCRIPTION: When the '*' (star) character is seen as a command in the batch file, the remain characters on the line are skipped over and processing begins with the next line. The comment is not printed on the screen to the user and is intended only to provide helpful information within the batch file. RELATED COMMANDS: none EXAMPLES: BAT * This is a comment. BAT TYPE This is a text line on the screen. BAT * This text line is a comment to the programmer. PROGRAMMING TIPS AND TECHNIQUES _______________________________ Use SKIP instead of GOTO when doing forward references where ever possible. Try to have loops in the batch file near the beginning. These will execute faster. Remember that GOTO's scan the entire batch file starting from the top. If the matching label is near the bottom, a slight delay will be seen. 16 Be cautious with the following types of lines: 1. Lines that use %R (return codes) 2. Assignment commands (e.g. %1 = XYZ) These two types of lines CANNOT be used immediately after a DOS command. This is because that DOS commands will do substitutions for variables before BAT has a chance to execute. Because of this, substitutions will not be properly done for these two types of batch file lines. If it is necessary to do this type of function, then put in a line that just contains the word 'BAT' between the DOS command line and the suspect BAT line. This will cause BAT to be reloaded before executing the suspect line. That is . . . This is illegal: BAT * The following is a dos command. DIR B:*.* BAT TYPE The current return code is %R This is legal: BAT * The following is a dos command. DIR B:*.* BAT BAT TYPE The current return code is %R It is unfortunate that this restriction exists, however, it is unavoidable unless COMMAND.COM is to be rewritten (which I don't plan on doing!). 17 doing!).